'\" te
.\" Copyright (c) 1993, Sun Microsystems, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SYNCSTAT 8 "March 6, 2023"
.SH NAME
syncstat \- report driver statistics from a synchronous serial link
.SH SYNOPSIS
.nf
\fB/usr/sbin/syncstat\fR [\fB-c\fR] \fIdevice\fR [\fIinterval\fR]
.fi

.SH DESCRIPTION
The \fBsyncstat\fR command reports the event statistics maintained by a
synchronous serial device driver. The report may be a single snapshot of the
accumulated totals, or a series of samples showing incremental changes. Prior
to these it prints the device name being used to query a particular device
driver, along with a number indicating the channel number (ppa) under control
of that driver.
.sp
.LP
Event statistics are maintained by a driver for each physical channel that it
supports. They are initialized to zero at the time the driver module is loaded
into the system, which may be either at boot time or when one of the driver's
entry points is first called.
.sp
.LP
The  \fIdevice\fR argument is the name of the serial device as it appears in
the \fB/dev\fR directory.  For example,  \fBzsh0\fR specifies the first
on-board serial device.
.sp
.LP
The following is a breakdown of  \fBsyncstat\fR output:
.sp

.sp
.TS
l l
l l .
\fBspeed\fR	T{
The line speed the device has been set to operate at. It is the user's responsibility to make this value correspond to the modem clocking speed when clocking is provided by the modem.
T}
\fBipkts\fR	The total number of input packets.
\fBopkts\fR	The total number of output packets.
\fBundrun\fR	T{
The number of transmitter underrun errors.
T}
\fBovrrun\fR	The number of receiver overrun errors.
\fBabort\fR	The number of aborted received frames.
\fBcrc\fR	T{
The number of received frames with CRC errors.
T}
\fBisize\fR	T{
The average size (in bytes) of input packets.
T}
\fBosize\fR	T{
The average size (in bytes) of output packets.
T}
.TE

.SH OPTIONS
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.RS 12n
Clear the accumulated statistics for the device specified. This may be useful
when it is not desirable to unload a particular driver, or when the driver is
not capable of being unloaded.
.RE

.sp
.ne 2
.na
\fB\fIinterval\fR\fR
.ad
.RS 12n
\fBsyncstat\fR samples the statistics every  \fIinterval\fR seconds and reports
incremental changes. The output reports line utilization for input and output
in place of average packet sizes. These are the relationships between bytes
transferred and the baud rate, expressed as percentages. The loop repeats
indefinitely, with a column heading printed every twenty lines for convenience.
.RE

.SH EXAMPLES
\fBExample 1 \fRSample output from the \fBsyncstat\fR command:
.sp
.in +2
.nf
example# \fBsyncstat zsh0\fR


speed ipkts opkts undrun ovrrun abort crc isize osize
9600  15716 17121   0      0      1    3   98    89
.fi
.in -2
.sp

.sp
.in +2
.nf
example# \fBsyncstat \fR\fB-c\fR\fB zsh0\fR

speed ipkts opkts undrun ovrrun abort crc isize osize
9600   0     0     0      0      0     0    0     0
.fi
.in -2
.sp

.sp
.LP
In the following sample output a new line of output is generated every five
seconds:

.sp
.in +2
.nf
example# \fBsyncstat zsh0 5\fR

ipkts opkts undrun ovrrun abort crc iutil outil
12    10      0     0      0     0   5%    4%
22    60      0     0      0     0   3%    90%
36    14      0     0      0     1   51%   2%
.fi
.in -2
.sp

.SH SEE ALSO
.BR attributes (7),
.BR syncinit (8),
.BR syncloop (8)
.SH DIAGNOSTICS
.ne 2
.na
\fB\fBbad interval: \fR\fIarg\fR\fR
.ad
.sp .6
.RS 4n
The argument  \fIarg\fR is expected to be an interval and could not be
understood.
.RE

.sp
.ne 2
.na
\fB\fIdevice\fR\fB missing minor device number\fR\fR
.ad
.sp .6
.RS 4n
The name  \fIdevice\fR does not end in a decimal number that can be used as a
minor device number.
.RE

.sp
.ne 2
.na
\fB\fBbaud rate not set\fR\fR
.ad
.sp .6
.RS 4n
The  \fIinterval\fR option is being used and the baud rate on the device is
zero. This would cause a divide-by-zero error when computing the line
utilization statistics.
.RE

.SH WARNINGS
Underrun, overrun, frame-abort, and CRC errors have a variety of causes.
Communication protocols are typically able to handle such errors and initiate
recovery of the transmission in which the error occurred. Small numbers of such
errors are not a significant problem for most protocols. However, because the
overhead involved in recovering from a link error can be much greater than that
of normal operation, high error rates can greatly degrade overall link
throughput. High error rates are often caused by problems in the link hardware,
such as cables, connectors, interface electronics or telephone lines. They may
also be related to excessive load on the link or the supporting system.
.sp
.LP
The percentages for input and output line utilization reported when using the
\fIinterval\fR option may occasionally be reported as slightly greater than
100% because of inexact sampling times and differences in the accuracy between
the system clock and the modem clock. If the percentage of use greatly exceeds
100%, or never exceeds 50%, then the baud rate set for the device probably does
not reflect the speed of the modem.
